/*
// =====================================================================================
// 
//       Filename:  elib_time.hpp
// 
//    Description:  
// 
//        Version:  1.0
//        Created:  10/25/2013 09:12:51 AM
//       Revision:  none
//       Compiler:  g++
// 
//         Author:  Elwin.Gao (elwin), elwin.gao4444@gmail.com
//        Company:  
// 
// =====================================================================================
*/

#ifndef  _ELIB_TIME_H_
#define  _ELIB_TIME_H_

#include "elib_util.hpp"

// =====================================================================================
//        Class:  EL_Time
//  Description:  时间处理类
// =====================================================================================
class EL_Time
{
public:
	// ====================  INTERFACE     =======================================
	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  get_time_string
	//  Description:  返回系统默认格式的当前时间，并且保证总是执行成功
	//   Parameters:  user_time: 用户指定时间（time_t类型），-1或不指定，则使用当前时间
	//                user_buf: 用户指定缓冲区，不指定则使用默认缓存
	//  ReturnValue:  返回格式化时间的字符串首地址
	// =====================================================================================
	*/
	char* date_string(time_t user_time = -1, char *user_buf = NULL);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  date_format
	//  Description:  将日期格式化输出
	//   Parameters:  format: 指定输出格式（所有格式标记字符大小写敏感）
	//                format串要求必须以'\0'结尾
	//                          YY: 保留年份的后2位，小于10时，以0补全2位
	//                        YYYY: 保留年份的全4位，不足4位时，以0补全4位
	//
	//                           M: 显示月份，1-9月时只显示1位数字
	//                          MM: 显示月份，1-9月时以0补全2位数字
	//                        MMEN: 显示月份，以3个字母的英文显示月份
	//
	//                           D: 显示日期，1-9日时只显示1位数字
	//                          DD: 显示日期，1-9日时以0补全2位数字
	//                        DDEN: 显示日期，以3个字母的英文显示日期 
	//
	//
	//                           h: 显示小时，0-9时只显示1位数字（默认为24小时制）
	//                         h12: 12小时制显示小时，0-9时只显示1位数字
	//                          hh: 显示小时，0-9时以0补全2位数字（默认为24小时制）
	//                        hh12: 12小时制显示小时，0-9时以0补全2位数字
	//                        hmen: hours mark: 根据当前时间显示AM或PM
	//                        hmcn: hours mark: 根据当前时间显示中文时间划分
	//                    时间划分: 凌晨(1-4)、早晨(5-7)、上午(8-11)、中午(12-12)、下午(13-18)、晚上(19-22)、夜间(23-0)
	//
	//                           m: 显示分钟，0-9分时只显示1位数字
	//                          mm: 显示分钟，0-9分时以0补全2位数字
	//
	//                           s: 显示秒数，0-9秒时只显示1位数字
	//                          ss: 显示秒数，0-9秒时以0补全2位数字
	//
	//
	//                           W: 显示星期，以数字1-7表示
	//                         WEN: 显示星期，以3个英文字母表示
	//                         WCN: 显示星期，以3个中文汉字表示
	//
	//
	//                       TZONE: 显示当前使用的时区，形如：UTC+8表示东8区	(涉及BSD扩展，暂不支持)
	//                       TZNMK: 显示当前使用的计时标准，形如：UTC，GTM，CST，......	(涉及BSD扩展，暂不支持)
	//
	//                数值表示形式: 所有数值默认以阿拉伯数字显示，
	//                               SDGT|: 前缀，以阿拉伯数字显示
	//                               SCNS|: 前缀，以简体中文数字及相关文字
	//                               SCNT|: 前缀，以繁体中文数字及相关文字
	//
	//                user_time: 用户指定时间（time_t类型），-1或不指定，则使用当前时间
	//                zone_amend: 对当前时区进行修正，默认修正为0
	//  ReturnValue:  返回格式化时间的字符串首地址，失败返回NULL
	//         Note:  默认缓冲区长度为64字节，不做越界检测，如果输出字符过长，必须使用自定义缓冲区
	// =====================================================================================
	*/
	char* date_format(const char *format, time_t user_time = -1, int zone_amend = 0);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  date_format
	//  Description:  将日期格式化输出
	//   Parameters:  format: 指定输出格式
	//                user_buf: 用户指定缓冲区
	//                user_time: 用户指定时间（time_t类型），-1或不指定，则使用当前时间
	//                zone_amend: 对当前时区进行修正，默认修正为0
	//  ReturnValue:  返回格式化时间的字符串的长度
	//         Note:  默认缓冲区长度为64字节，不做越界检测，如果输出字符过长，必须使用自定义缓冲区
	// =====================================================================================
	*/
	long date_format(const char *format, char *user_buf, time_t user_time = -1, int zone_amend = 0);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  time_format
	//  Description:  将时长格式化输出（秒为单位）
	//   Parameters:  user_time: 用户指定的时间
	//                format: 时间输出格式
	//                          dd: 显示天数
	//                          hh: 显示小时数
	//                          mm: 显示分钟数
	//                          ss:	显示秒数
	//
	//                        前缀: NZ(n): 指定如果数值为空，则不显示。最后的数值表示附带不显示的长度
	//                                ALL: 指定当前数值不向更高的单位进位
	//
	//                        后缀:     n: 指定对齐位数，不足位以0填充
	//  ReturnValue:  返回格式化时间的字符串首地址，失败返回NULL
	// =====================================================================================
	*/
	char* time_format(time_t user_time, const char *format);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  time_format
	//  Description:  将时长格式化输出（秒为单位）
	//   Parameters:  user_time: 用户指定的时间
	//                format: 时间输出格式
	//                user_buf: 用户指定缓冲区
	//  ReturnValue:  返回格式化时间的字符串首地址，失败返回NULL
	// =====================================================================================
	*/
	long time_format(time_t user_time, const char *format, char *user_buf);

	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  set_time_begin
	//  Description:  设置计时器起点，成功返回0，失败返回-1
	// =====================================================================================
	*/
	int   set_time_begin();

	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  set_time_end
	//  Description:  设置计时器终点，成功返回0，失败返回-1
	// =====================================================================================
	*/
	int   set_time_end();

	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  diff_time_ms
	//  Description:  获得以毫秒为单位的计时结果，保证执行结果总是成功
	// =====================================================================================
	*/
	long  diff_time_ms();

	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  diff_time_format
	//  Description:  获得格式化(0000h:00m:00s:000ms)的计时结果，保证执行结果总是成功
	// =====================================================================================
	*/
	char* diff_time_format();

	/*
	// ===  FUNCTION  ======================================================================
	//         Name:  reset
	//  Description:  重置计时器
	// =====================================================================================
	*/
	void reset();

private:
	// ==================== PRIVATE METHOD =======================================

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  write_number
	//  Description:  封装date_format中的日期输出功能
	//   Parameters:  pbuf: 输出缓冲区
	//                digit: 输出数值
	//                digit_type: 输出类型（0-阿拉伯数字，1-中文小写，2-中文大写）
	//                align: 对齐标志（是否按2字节对齐）
	//  ReturnValue:  void
	// =====================================================================================
	*/
	void write_date(char *&pbuf, int digit, int digit_type, bool align);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  do_date_format
	//  Description:  为date_format的重载提供核心功能
	//   Parameters:  format: 输出格式（详见date_format）
	//                user_time: 用户指定时间（time_t类型），-1或不指定，则使用当前时间
	//                user_buf: 用户指定缓冲区，不指定则使用默认缓存
	//                zone_amend: 对当前时区进行修正，默认修正为0
	//  ReturnValue:  返回输出结束的尾指针(指向'\0')
	// =====================================================================================
	*/
	char* do_date_format(const char *format, char *user_buf = NULL, time_t user_time = -1, int zone_amend = 0);

	/* 
	// ===  FUNCTION  ======================================================================
	//         Name:  do_time_format
	//  Description:  将时长格式化输出
	//   Parameters:  user_time: 用户指定的时间
	//                format: 时间输出格式（详见time_format）
	//                user_buf: 用户指定缓冲区，不指定则使用默认缓存
	//  ReturnValue:  返回格式化时间的字符串首地址，失败返回NULL
	// =====================================================================================
	*/
	char* do_time_format(time_t user_time, const char *format, char *user_buf = NULL);

	// ====================  DATA MEMBERS  =======================================
	static const long buf_len = 64;		// 默认缓冲区大小
	static const char* en_month[13];	// 英文月份简写
	static const char* cn_month[13];	// 中文月份简写
	static const char* en_day[32];		// 英文日期
	static const char* en_week[8];		// 英文星期简写
	static const char* cn_week[8];		// 中文星期简写
	static const char* simp_number[60];	// 简体中文数字
	static const char* trad_number[60];	// 繁体中文数字
	static const char* simp_time_division[24];	// 中文时间划分
	static const char* trad_time_division[24];	// 中文时间划分

	struct timeval time_begin;
	struct timeval time_end;
	char time_buf[buf_len];

};		// -----  end of class EL_Time  -----

#endif   // ----- #ifndef _ELIB_TIME_H_  -----
